home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kicontheme.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  9.7 KB  |  369 lines
  1. /* vi: ts=8 sts=4 sw=4
  2.  *
  3.  * This file is part of the KDE project, module kdecore.
  4.  * Copyright (C) 2000 Geert Jansen <jansen@kde.org>
  5.  *                    Antonio Larrosa <larrosa@kde.org>
  6.  *
  7.  * This is free software; it comes under the GNU Library General
  8.  * Public License, version 2. See the file "COPYING.LIB" for the
  9.  * exact licensing terms.
  10.  *
  11.  */
  12.  
  13. #ifndef __KIconTheme_h_Included__
  14. #define __KIconTheme_h_Included__
  15.  
  16. #include <qstring.h>
  17. #include <qstringlist.h>
  18. #include <qptrlist.h>
  19. #include "kdelibs_export.h"
  20.  
  21. class KConfig;
  22. class KIconThemeDir;
  23.  
  24. class KIconThemePrivate;
  25.  
  26. class KIconPrivate;
  27.  
  28. /**
  29.  * One icon as found by KIconTheme. Also serves as a namespace containing
  30.  * icon related constants.
  31.  * @see KIconEffect
  32.  * @see KIconTheme
  33.  * @see KIconLoader
  34.  */
  35. class KDECORE_EXPORT KIcon
  36. {
  37. public:
  38.     KIcon() { size = 0; }
  39.  
  40.     /**
  41.      * Return true if this icon is valid, false otherwise.
  42.      */
  43.     bool isValid() const { return size != 0; }
  44.  
  45.     /**
  46.      * Defines the context of the icon.
  47.      */
  48.     enum Context {
  49.       Any, ///< Some icon with unknown purpose.
  50.       Action, ///< An action icon (e.g. 'save', 'print').
  51.       Application, ///< An icon that represents an application.
  52.       Device, ///< An icon that represents a device.
  53.       FileSystem, ///< An icon that represents a file system.
  54.       MimeType, ///< An icon that represents a mime type (or file type).
  55.       Animation, ///< An icon that is animated.
  56.       Category, ///< An icon that represents a category.
  57.       Emblem, ///< An icon that adds information to an existing icon.
  58.       Emote, ///< An icon that expresses an emotion.
  59.       International, ///< An icon that represents a country's flag.
  60.       Place, ///< An icon that represents a location (e.g. 'home', 'trash').
  61.       StatusIcon ///< An icon that represents an event.
  62.     };
  63.  
  64.     /**
  65.      * The type of the icon.
  66.      */
  67.     enum Type {
  68.       Fixed, ///< Fixed-size icon.
  69.       Scalable, ///< Scalable-size icon.
  70.       Threshold ///< A threshold icon.
  71.     };
  72.  
  73.     /**
  74.      * The type of a match.
  75.      */
  76.     enum MatchType {
  77.       MatchExact, ///< Only try to find an exact match.
  78.       MatchBest   ///< Take the best match if there is no exact match.
  79.  
  80.     };
  81.  
  82.     // if you add a group here, make sure to change the config reading in
  83.     // KIconLoader too
  84.     /**
  85.      * The group of the icon.
  86.      */
  87.     enum Group {
  88.     /// No group
  89.     NoGroup=-1,
  90.     /// Desktop icons
  91.     Desktop=0,
  92.     /// First group
  93.     FirstGroup=0,
  94.     /// Toolbar icons
  95.     Toolbar,
  96.     /// Main toolbar icons
  97.         MainToolbar,
  98.     /// Small icons
  99.     Small,
  100.     /// Panel (Kicker) icons
  101.     Panel,
  102.     /// Last group
  103.     LastGroup,
  104.     /// User icons
  105.     User
  106.          };
  107.  
  108.     /**
  109.      * These are the standard sizes for icons.
  110.      */
  111.     enum StdSizes {
  112.         /// small icons for menu entries
  113.         SizeSmall=16,
  114.         /// slightly larger small icons for toolbars, panels, etc
  115.         SizeSmallMedium=22,
  116.         /// medium sized icons for the desktop
  117.         SizeMedium=32,
  118.         /// large sized icons for the panel
  119.         SizeLarge=48,
  120.         /// huge sized icons for iconviews
  121.         SizeHuge=64,
  122.         /// enormous sized icons for iconviews
  123.         SizeEnormous=128
  124.          };
  125.  
  126.     /**
  127.      * Defines the possible states of an icon.
  128.      */
  129.     enum States { DefaultState, ///< The default state.
  130.           ActiveState,  ///< Icon is active.
  131.           DisabledState, ///< Icon is disabled.
  132.           LastState      ///< Last state (last constant)
  133.     };
  134.  
  135.     /**
  136.      * This defines an overlay, a semi-transparent image that is
  137.      * projected onto the icon. They are used to show that the file
  138.      * represented by the icon is, for example, locked, zipped or hidden.
  139.      */
  140.     enum Overlays {
  141.       LockOverlay=0x100, ///< a file is locked
  142.       ZipOverlay=0x200,  ///< a file is zipped
  143.       LinkOverlay=0x400, ///< a file is a link
  144.       HiddenOverlay=0x800, ///< a file is hidden
  145.       ShareOverlay=0x1000, ///< a file is shared
  146.       OverlayMask = ~0xff
  147.     };
  148.  
  149.     /**
  150.      * The size in pixels of the icon.
  151.      */
  152.     int size;
  153.  
  154.     /**
  155.      * The context of the icon.
  156.      */
  157.     Context context;
  158.  
  159.     /**
  160.      * The type of the icon: Fixed, Scalable or Threshold.
  161.      **/
  162.     Type type;
  163.  
  164.     /**
  165.      * The threshold in case type == Threshold
  166.      */
  167.     int threshold;
  168.  
  169.     /**
  170.      * The full path of the icon.
  171.      */
  172.     QString path;
  173.  
  174. private:
  175.     KIconPrivate *d;
  176. };
  177.  
  178. inline KIcon::Group& operator++(KIcon::Group& group) { group = static_cast<KIcon::Group>(group+1); return group; }
  179. inline KIcon::Group operator++(KIcon::Group& group,int) { KIcon::Group ret = group; ++group; return ret; }
  180.  
  181. /**
  182.  * Class to use/access icon themes in KDE. This class is used by the
  183.  * iconloader but can be used by others too.
  184.  * @see KIconLoader
  185.  */
  186. class KDECORE_EXPORT KIconTheme
  187. {
  188. public:
  189.     /**
  190.      * Load an icon theme by name.
  191.      * @param name the name of the theme (e.g. "hicolor" or "keramik")
  192.      * @param appName the name of the application. Can be null. This argument
  193.      *        allows applications to have themed application icons.
  194.      */
  195.     KIconTheme(const QString& name, const QString& appName=QString::null);
  196.     ~KIconTheme();
  197.  
  198.     /**
  199.      * The stylized name of the icon theme.
  200.      * @return the (human-readable) name of the theme
  201.      */
  202.     QString name() const { return mName; }
  203.  
  204.     /**
  205.      * A description for the icon theme.
  206.      * @return a human-readable description of the theme, QString::null
  207.      *         if there is none
  208.      */
  209.     QString description() const { return mDesc; }
  210.  
  211.     /**
  212.      * Return the name of the "example" icon. This can be used to
  213.      * present the theme to the user.
  214.      * @return the name of the example icon, QString::null if there is none
  215.      */
  216.     QString example() const;
  217.  
  218.     /**
  219.      * Return the name of the screenshot.
  220.      * @return the name of the screenshot, QString::null if there is none
  221.      */
  222.     QString screenshot() const;
  223.  
  224.     /**
  225.      * Returns the name of this theme's link overlay.
  226.      * @return the name of the link overlay
  227.      */
  228.     QString linkOverlay() const;
  229.  
  230.     /**
  231.      * Returns the name of this theme's zip overlay.
  232.      * @return the name of the zip overlay
  233.      */
  234.     QString zipOverlay() const;
  235.  
  236.     /**
  237.      * Returns the name of this theme's lock overlay.
  238.      * @return the name of the lock overlay
  239.      */
  240.     QString lockOverlay() const;
  241.  
  242.     /**
  243.      * Returns the name of this theme's share overlay.
  244.      * @return the name of the share overlay
  245.      * @since 3.1
  246.      */
  247.     QString shareOverlay () const;
  248.  
  249.     /**
  250.      * Returns the toplevel theme directory.
  251.      * @return the directory of the theme
  252.      */
  253.     QString dir() const { return mDir; }
  254.  
  255.     /**
  256.      * The themes this icon theme falls back on.
  257.      * @return a list of icon themes that are used as fall-backs
  258.      */
  259.     QStringList inherits() const { return mInherits; }
  260.  
  261.     /**
  262.      * The icon theme exists?
  263.      * @return true if the icon theme is valid
  264.      */
  265.     bool isValid() const;
  266.  
  267.     /**
  268.      * The icon theme should be hidden to the user?
  269.      * @return true if the icon theme is hidden
  270.      * @since 3.1
  271.      */
  272.     bool isHidden() const;
  273.  
  274.     /**
  275.      * The minimum display depth required for this theme. This can either
  276.      * be 8 or 32.
  277.      * @return the minimum bpp (8 or 32)
  278.      */
  279.     int depth() const { return mDepth; }
  280.  
  281.     /**
  282.      * The default size of this theme for a certain icon group.
  283.      * @param group The icon group. See KIcon::Group.
  284.      * @return The default size in pixels for the given icon group.
  285.      */
  286.     int defaultSize(KIcon::Group group) const;
  287.  
  288.     /**
  289.      * Query available sizes for a group.
  290.      * @param group The icon group. See KIcon::Group.
  291.      * @return a list of available sized for the given group
  292.      */
  293.     QValueList<int> querySizes(KIcon::Group group) const;
  294.  
  295.     /**
  296.      * Query available icons for a size and context.
  297.      * @param size the size of the icons
  298.      * @param context the context of the icons
  299.      * @return the list of icon names
  300.      */
  301.     QStringList queryIcons(int size, KIcon::Context context = KIcon::Any) const;
  302.  
  303.     /**
  304.      * Query available icons for a context and preferred size.
  305.      * @param size the size of the icons
  306.      * @param context the context of the icons
  307.      * @return the list of icon names
  308.      */
  309.     QStringList queryIconsByContext(int size, KIcon::Context context = KIcon::Any) const;
  310.  
  311.  
  312.     /**
  313.      * Lookup an icon in the theme.
  314.      * @param name The name of the icon, without extension.
  315.      * @param size The desired size of the icon.
  316.      * @param match The matching mode. KIcon::MatchExact returns an icon
  317.      * only if matches exactly. KIcon::MatchBest returns the best matching
  318.      * icon.
  319.      * @return A KIcon class that describes the icon. If an icon is found,
  320.      * @see KIcon::isValid will return true, and false otherwise.
  321.      */
  322.     KIcon iconPath(const QString& name, int size, KIcon::MatchType match) const;
  323.     
  324.     /**
  325.      * Returns true if the theme has any icons for the given context.
  326.      * @since 3.5.5
  327.      */
  328.     bool hasContext( KIcon::Context context ) const;
  329.  
  330.     /**
  331.      * List all icon themes installed on the system, global and local.
  332.      * @return the list of all icon themes
  333.      */
  334.     static QStringList list();
  335.  
  336.     /**
  337.      * Returns the current icon theme.
  338.      * @return the name of the current theme
  339.      */
  340.     static QString current();
  341.  
  342.     /**
  343.      * Reconfigure the theme.
  344.      */
  345.     static void reconfigure();
  346.  
  347.     /**
  348.      * Returns the default icon theme.
  349.      * @return the name of the default theme name
  350.      * @since 3.1
  351.      */
  352.     static QString defaultThemeName();
  353.  
  354. private:
  355.     int mDefSize[8];
  356.     QValueList<int> mSizes[8];
  357.  
  358.     int mDepth;
  359.     QString mDir, mName, mDesc;
  360.     QStringList mInherits;
  361.     QPtrList<KIconThemeDir> mDirs;
  362.     KIconThemePrivate *d;
  363.  
  364.     static QString *_theme;
  365.     static QStringList *_theme_list;
  366. };
  367.  
  368. #endif
  369.